home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource3 / 123_01 / dio.doc < prev    next >
Text File  |  1985-03-11  |  11KB  |  443 lines
  1. .bp 1
  2. .in 0
  3. .he 'DIO (3)'03/10/83'DIO (3)'
  4. .fo ''-#-''
  5. .fi
  6. .in 7
  7. .ne 6
  8. .ti -7
  9. NAME
  10. .br
  11. dio - directed I/O for BDS C
  12.  
  13.  
  14. .ne 6
  15. .ti -7
  16. SYNOPSIS
  17.  
  18. .nf
  19. #include bdscio.h
  20. #include dio.h
  21.  
  22. main(argc, argv)
  23. int argc;
  24. char **argv;
  25. {
  26.     /* calls to wildexp() and dioinit() can be reversed. */
  27.  
  28.     _allocp = NULL;        /* initialize storage allocation */
  29.     dioinit(&argc, argv);    /* direct I/O streams (required) */
  30.     wildexp(&argc, &argv);    /* expand wild cards (optional)  */
  31.     main1(argc, argv);    /* do the real work         */
  32.     dioflush();        /* no error if we get here     */
  33. }    
  34. .br
  35. .fi
  36.  
  37.  
  38. .ne 6
  39. .ti -7
  40. DESCRIPTION
  41.  
  42. Dio is a package which, when linked together with a BDS C program,
  43. provides that program with the following unix-like features:
  44.  
  45. .nf
  46. o  I/O redirection on the command line
  47. o  Pipes specified on the command line
  48. o  I/O directed to special files
  49. o  Wildcard expansion of file names (optional)
  50. .br
  51. .fi
  52.  
  53. To use these features a program must follow the synopsis above.
  54.  
  55. The version of DIO described here
  56. is an extension of the original version supplied
  57. with the BDS C compiler.
  58.  
  59.  
  60. .ne 6
  61. .ce
  62. I/O REDIRECTION AND PIPES
  63.  
  64. You may activate redirection and pipes using five special arguments
  65. on the command line:
  66.  
  67. .ne 4
  68. .in +5
  69. .ti -5
  70. >foo
  71. .br
  72. Causes all standard output to go to the file "foo" instead of the console.
  73. In particular, causes putchar() and putc(c, STD_OUT) to go to "foo".
  74.  
  75. .ne 4
  76. .ti -5
  77. +foo
  78. .br
  79. Like >foo except that the characters are ALSO
  80. sent to the console.
  81.  
  82. .ne 4
  83. .ti -5
  84. @foo
  85. .br
  86. Causes all output to the standard error stream
  87. to be sent to foo.
  88. In particular, causes putc(c, STD_ERR) to go to "foo".
  89.  
  90. .ne 4
  91. .ti -5
  92. <foo
  93. .br
  94. Causes all input from the standard input stream to come from file "foo".
  95. In particular,
  96. causes getchar() to return characters from the
  97. file named "foo" instead of from the keyboard.
  98.  
  99. .ne 4
  100. .ti -5
  101. command |prog
  102. .br
  103. Causes the standard output of the command
  104. specified in "command" to be fed into the
  105. standard input of another program, "prog."
  106. (BOTH "command" and "prog" must be compiled
  107. with dio).
  108. Multiple pipes may be chained on one command line.
  109. .br
  110. .in -5
  111.  
  112. Warning: redirection and pipes work only for TEXT.
  113. This mechanism should not be used for binary data.
  114.  
  115. There must never be any spaces between >,+,<,@ or | and the
  116. corresponding filename.
  117.  
  118. When no "<" or "|" operator is used, standard input comes from the
  119. console and all standard line editing characters are recognized.
  120. To indicate end-of-file, you must type
  121. .br
  122. ^Z <CR>  (control-Z followed by    a carriage-return.)
  123.  
  124. When no ">" or "|" operator is used, standard output goes to the
  125. console.
  126.  
  127.  
  128. .ne 6
  129. .ce
  130. SPECIAL FILES
  131.  
  132. Special files are jargon for I/O devices (like printers or consoles)
  133. which appear to a program to be a disk file.
  134. There are two special files, namely PRINTER and TTY.
  135.  
  136. .ne 7
  137. These special files can be named on the command line:
  138.  
  139. .nf
  140.      >printer  sends STD_OUT to the printer.
  141.      @printer  sends ERR_OUT to the printer.
  142.      >tty      sends STD_OUT to the user's console.
  143.      @tty      sends ERR_OUT to the user's console.
  144.      <tty      gets  STD_IN from the user's console.
  145. .br
  146. .fi
  147.  
  148. For obvious reasons, input can not be gotten from the printer.
  149.  
  150. .ne 3
  151. The dio package also provides a way for a program to direct
  152. I/O to a particular device, regardless of the command-line settings.
  153. Input directed from DEV_TTY always comes from the user's console.
  154. Output directed to DEV_TTY always goes to the user's console.
  155. Output directed to DEV_LST always goes to the printer.
  156.  
  157. .ne 3
  158. .nf
  159.      c = getc(DEV_TTY);   ALWAYS gets c from the user's console
  160.      putc(c, DEV_TTY);    ALWAYS prints c on the user's console
  161.      putc(c, DEV_LST);    ALWAYS prints c on the printer
  162. .br
  163. .fi
  164.  
  165.  
  166. .ne 6
  167. .ce
  168. WILDCARDS
  169.  
  170. Wildexp() expands ambiguous file names (afn's) on the command line
  171. into a list of files which match the afn.
  172. Note that wildcard expansion should NOT be used for programs
  173. that use command-line arguments containing '*' or '?' to denote something
  174. besides file names.
  175. Examples would be the translit (tr) search (grep) or change (gres) utilities
  176. which use '*' and '?' in text patterns on the command line.
  177.  
  178. An afn preceded by a "!" causes all names matching the given
  179. afn to be EXCLUDED from the resulting expansion list.
  180.  
  181. When giving a "!" afn, "*" chars in the string matches to the
  182. end of either the filename or extension, just like CP/M,
  183. but "?" chars match ONE and ONLY ONE character in either
  184. the filename or extension.
  185.  
  186.  
  187. .ne 6
  188. .ce
  189. THE DIRECTED I/O LIBRARY
  190.  
  191. The following functions make up the directed I/O library.
  192.  
  193. .in +5
  194. .ne 4
  195. .ti -5
  196. dioinit(&argc, argv)
  197. .br
  198. Make this (or wildexp) the first routine that your main program calls.
  199. Dioinit() reads the command line and redirects I/O if requested.
  200. Any arguments that start with '<' '>' '+' '@' or '|' become invisible
  201. after this call.
  202.  
  203. .ne 4
  204. .ti -5
  205. dioflush()
  206. .br
  207. Flushes and closes all directed output files (if any).
  208. Make sure you call dioflush() whenever you exit the program.
  209. On abnormal termination, call dioflush() before calling exit().
  210.  
  211. .ne 4
  212. .ti -5
  213. getchar()
  214. .br
  215. Gets a character from the console
  216. or from a directed input file (or special file) if one
  217. was specified on the command line.
  218.  
  219. .ne 4
  220. .ti -5
  221. putchar(c)
  222. .br
  223. Puts a character out to the console,
  224. or to a directed output file (or special file) if one
  225. was specified on the command line.
  226.  
  227. .ne 4
  228. .ti -5
  229. putc(c, file)
  230. .br
  231. Puts a character to a file (or special file).
  232. This routine was not included in the old dio package.
  233.  
  234. .ne 4
  235. .ti -5
  236. wildexp(&argc, &argv)
  237. .br 
  238. Expands ambiguous file names into a list of unambiguous file names.
  239. Wildexp() can be called before the call to dioinit() if desired.
  240.  
  241. You must initialize the variable _allocp to NULL before calling wildexp().
  242. Note that wildexp() uses sbrk() to obtain storage so don't go playing
  243. around with memory that is outside the external or stack areas unless
  244. you obtain the memory through sbrk() or alloc() calls.
  245. .br
  246. .in -5
  247.  
  248.  
  249. .ne 6
  250. .ti -7
  251. EXAMPLES
  252.  
  253. Multiple pipes may be chained on one command line.
  254. The following command feeds the output of program "foo" into the
  255. input of program "bar", the output of "bar" into the input of
  256. program "zot", and the output of "zot" into a file called "output":
  257.  
  258.     A>foo arg1 |bar |zot arg2 arg3 >output
  259.  
  260. "arg1" is an actual argument to "foo", and "arg2" and "arg3" are
  261. actual arguments to "zot". This illustrates how actual arguments
  262. may be interspersed with redirection commands. The programs see
  263. the actual arguments, but command line preprocessing handled by the
  264. "dioinit" function cause the programs to never need to know about
  265. the redirection commands. Note that all three programs ("foo", "bar"
  266. and "zot") must have been compiled and linked to use the "dio"
  267. package.
  268.  
  269. An afn preceded by a "!" causes all names matching the given
  270. afn to be EXCLUDED from the resulting expansion list.
  271. Thus, to yield a command line containing all files except
  272. "COM" files, you'd say:
  273.  
  274. .ce
  275. progname !*.com <cr>
  276.  
  277. To get all files on B: except .C files, say:
  278.  
  279. .ce
  280. prognam b:*.* !b:*.c <cr>
  281.  
  282.  
  283. .ne 6
  284. .ti -7
  285. FILES
  286.  
  287. .nf
  288. printer, tty (special files)
  289. tempin.$$$, tempout.$$$ (created for pipes)
  290. .fi
  291.  
  292.  
  293. .ne 6
  294. .ti -7
  295. SEE ALSO
  296.  
  297. file, rawfile and args on the Software Tools Disk
  298.  
  299.  
  300. .ne 6
  301. .ti -7
  302. DIAGNOSTICS
  303.  
  304. .in +5
  305. .br
  306. .ti -5
  307. "Can't open"
  308. .br
  309. The file whose name follows a '<' does not exist.
  310. .br
  311. .ti -5
  312. "Can't create"
  313. .br
  314. The file whose name follows a '>' or '@' could not
  315. be created.
  316. The disk is probably full.
  317. .br
  318. .ti -5
  319. "bad '<' redirection"
  320. .br
  321. A file name must follow a '<' on the command line.
  322. No intervening blanks are allowed.
  323. .br
  324. .ti -5
  325. "bad '@' redirection"
  326. .br
  327. A file name must follow a '@' on the command line.
  328. No intervening blanks are allowed.
  329. .br
  330. .ti -5
  331. "bad '>' redirection"
  332. .br
  333. A file name must follow a '>' on the command line.
  334. No intervening blanks are allowed.
  335. .br
  336. .ti -5
  337. "bad pipe specifier"
  338. .br
  339. The name of a program must follow a '|'.
  340. No intervening blanks are allowed.
  341. .br
  342. .ti -5
  343. "broken pipe"
  344. .br
  345. The program whose name follows a '|' could not be loaded.
  346. The .com file does not exist.
  347. .br
  348. .in -5
  349.  
  350.  
  351. .ne 6
  352. .ti -7
  353. AUTHORS
  354.  
  355. .nf
  356. Leor Zolman wrote the original dio and wildexp.
  357. Modifications by Edward K. Ream.
  358. .fi
  359.  
  360.  
  361. .ne 6
  362. .ti -7
  363. BUGS/DEFICIENCIES
  364.  
  365. 1.  Wildexp() leaves no way to "escape" from the
  366. conventions for I/O redirection.
  367. Names of files which start with '<' '>' '+' '@' or '|'
  368. are going to cause problems.
  369. One possibility:  use back slash as an escape character.
  370. Also, it would be good to allow \b to mean a blank in a file name.
  371. For example: read\bme.doc.
  372.  
  373. .ne 6
  374. 2.  It would be consistent to add two more special files,
  375. reader and punch:
  376.  
  377. .nf
  378.    <reader  would get STD_IN from the reader.
  379.    >punch   would put STD_OUT to the punch.
  380.    @punch   would put STD_ERR to the punch.
  381. .br
  382. .fi
  383.  
  384. At present, the code does NOT allow these options.
  385. The _dispec variable is not used at all right now,
  386. but it's in as a hint about how to redirect
  387. STD_IN from special files.
  388. Adding these changes would require
  389. a slight mod to getc() similar to the changes made to putc().
  390.  
  391.  
  392. .ne 6
  393. .ti -7
  394. NOTES
  395.  
  396. 1.  This dio package is upward compatible with the old version.
  397. In other words, you should be able to switch dio packages WITHOUT
  398. recompiling programs.
  399. All you need to do is relink using the new version of dio.
  400.  
  401. 2.  I (Edward K. Ream) urgently request that all those who submit
  402. a program to me as part of the Software Tools project use SOME
  403. version of dio (preferably this version).
  404. Please DO NOT use the old RATFOR primitives;
  405. they should die an immediate death.
  406.  
  407. 3.  Use "-f dio" to link the all programs using dio;
  408. this ensures that the proper
  409. versions of getchar(), putchar() and putc() are used.
  410. Do not define your own getchar(), putchar() or putc()
  411. or things will get confused.
  412.  
  413. 4.  The console input may be raw (unbuffered, one char. at a time) or
  414. buffered (entire line must be typed before chars are returned,
  415. allowing standard editing features, and characters come back one
  416. at a time AFTER the entire line is typed).
  417. The default is raw; to
  418. have buffered console input, uncomment the "#define BUF_CONS" line
  419. in dio.h and recompile this file and all files in your program.
  420.  
  421. 5.  Putchar() and putc() now check for ^S and ^C without
  422. calling BDOS.
  423. The actual checking is done by chkkey().
  424. On ^C chkkey() aborts any program in the pipe by calling dioflush()
  425. and exit().
  426. Since chkkey does all its work
  427. using calls to BIOS instead of BDOS, you can now ckeck for
  428. characters from the keyboard WITHOUT having BDOS echo them
  429. for you.
  430. On the other hand, this scheme is NOT usable with MP/M.
  431.  
  432. 6.  Output sent to DEV_TTY always goes to the console,
  433. regardless of whether STD_OUT has been redireced.
  434. Thus, DEV_TTY now works like STD_OUT used to work.
  435. I believe that this new version is closer to the
  436. UNIX spirit than the old.
  437. Basically, devices should never be re-directed while streams should be.
  438.  
  439. 7.  The putc() routine now has code for diablo printers and their
  440. ^C, ^F handshaking.
  441. You can turn on that code with #define ACKNAK 1 in dio.c.
  442. ne now has code for diablo printers and their
  443.